<html>
<head>
<link rel="stylesheet" href="../blueprint/screen.css" type="text/css" media="screen, projection">

<title>RasterLang</title>

<link rel="stylesheet" href="../css/styles.css" type="text/css" media="screen,print">

</head>
<body>
<div class="container">

<h1>RasterLang</h1>
<p>
Rasterlang is a plugin for <a href="http://www.qgis.org">Quantum GIS (QGIS)</a>
that performs mathematical operations on raster (grid) data.
</p>

<h1>Installation</h1>
<p>
There are some prerequisite python modules you should install to the python that Qgis is using:
<ul>
<li>Python bindings for <a href="http://www.gdal.org">Gdal</a></li>
<li><a href="http://pyparsing.wikispaces.com/">PyParsing</a>, which defines the language used</li>
<li><a href="http://numpy.scipy.org/">Numpy</a>, which does the processing.</li>
</ul>
</p>

<p>
The plugin is in my main repository -
add <code>http://www.maths.lancs.ac.uk/~rowlings/Qgis/Plugins/plugins.xml</code>
to your repository list.
</p>

<h1>Usage</h1>
<p>
When run from the plugin menu or toolbar icon, rasterlang presents a dialog like this:
</p>
<p>
<img src="rasterlang.png">
</p>
<p>
At the top is a list of loaded rasters, with rasters of the same size
and position grouped. Operations can only be carried out on rasters
within the same group - rasterlang does no resampling or interpolation.
</p>
<p>
Below this is a text entry line for the expression. As you enter an expression 
the system checks the syntax and updates the status line. 
When a valid
expression is entered the OK button is enabled. Clicking that runs the
calculation and a 'Save' dialog is presented. The resulting output is
a GeoTIFF file with the same size and position as the input rasters. Currently
no coordinate reference system data is respected. The file is then loaded 
as a Qgis layer.
</p>

<h1>Expressions</h1>
<p>
Expressions in rasterlang are written in a simple LISP-style
language. The basic form is an operator plus arguments enclosed in
parentheses, separated by spaces: <code>( op arg1 arg2 ... )</code>,
but each argument can also be another expression. Simple arguments 
can be numbers or layers, referenced by the layer <em>label</em>. There are
also two constants 'Pi' and 'e'. If there are layers named 'Pi' or 'e' then
something bad will probably happen. So rename them.
</p>
<p>
Since layers in Qgis do not need to have unique names, and can be
named things like '2.0' or '---', we need a unique alpha-numeric label
for each layer. The second column in the rasterlang dialog gives this
label. If there are no conflicts then it will be the same as the name
of the layer, but if there are duplicates or characters that don't
make sense in the rasterlang syntax a unique name will be generated.
</p>
<p>
Here are some example expressions given the above layer set:
</p>

<table>
<tr><td><code>(+ b0 10)</code></td><td>Add 10 to layer b0</td></tr>
<tr><td><code>(+ b0 layer 12.34)</code></td><td>Add b0 and b1.tiff and
12.34</td></tr>
<tr><td><code>(exp ogclogo)</code></td><td>Take the exponential power
of ogclogo</td></tr>
<tr><td><code>(^ e ogclogo)</code></td><td>Take the exponential power
of ogclogo</td></tr>
<tr><td><code>(* Pi (^ ogclogo 2 ) )</code></td><td>'pi-r-squared' in rasterlang</td></tr>
<tr><td><code>(> layer-1 128)</code></td><td>Return a raster of 1
where ogc1.tiff is over 128, 0 elsewhere.</td></tr>
<tr><td><code>(* layer-1 (> layer-1 128) )</code></td><td>Like
ogc1.tiff, but zero below 128</td></tr>
<tr><td><code>(band MandSLetters 0)</code></td><td>Create a single
band raster from first band (band zero)</td></tr>
<tr><td><code>(bind b0 (+ 3 b0) (* 2 b0))</code></td><td>Create a
three band raster from manipulations of the single band in
b0</td></tr>
<tr><td><code>(bind (band MandSLetters 0) (* 1.3 (band MandSLetters 1)) (* 2.4 (band MandSLetters 2)))</code></td><td>Create a 3-band raster with scaled versions of the input layer bands.</td></tr>
</table>

<p>
And here are some invalid expressions:
</p>
<table>
<tr><td><code>+ 1 b0</code></td><td>Missing outer parentheses.</td></tr>
<tr><td><code>(+ 1 2)</code></td><td>No rasters specified.</td></tr>
<tr><td><code>(+ b0 ogclogo)</code></td><td>Rasters from different groups.</td></tr>
<tr><td><code>(+ b0 - 1)</code></td><td>Syntax error.</td></tr>
</table>

<h1>Operators</h1>
<p>
The help button gives a brief introduction to the syntax and also lists the valid operators. For 
each operator a short description is given and the valid number of arguments it needs.
</p>

<h1>Bugs</h1>
<ul>
<li>
I think you can get integer overflow if dealing with an integer raster. I should convert all to floating point.
</li>
<li>Sometimes the status line seems to not update properly and the OK button gets stuck enabled, this lets you enter bad expressions.</li>
<li>Some infix expressions seem to be valid syntax - such as <code>2+2</code> and <code>3-1</code>, but not <code>2*3</code>. Must be something in the parsing that's not right. These expressions should all be invalid, so don't use them.</li>
</ul>

<h1>Development</h1>
<p>
The code is maintained on my googlecode repository: <a href="http://code.google.com/p/bsrplugins/source/browse/#svn/trunk/rasterlang">browse the SVN</a>. I'll try and keep the <a href="http://code.google.com/p/bsrplugins/issues/list">issues list</a> up to date too. Contributions, such as new operators, are welcome.
</p>
<p>
I'd like to rewrite the syntax to something more pythonic. But this is the first time I've written a parser.
</p>

<h1>More Complex Raster Processing</h1>
<p>
If you need more complex raster processing then it's probably best done in Python. I have written <a href="python.html">some notes</a> on how to do this.
</p>

<h2>Credits</h2>
<p>
Written by Barry Rowlingson &lt;b.rowlingson@lancaster.ac.uk&gt;
</p>


</div>
</body>
</html>
